home *** CD-ROM | disk | FTP | other *** search
/ Power Tools 1993 October - Disc 2 / Power Tools (Disc 2)(October 1993)(HP).iso / hotlines / ccsyhl / sisfappl / sisfappl.txt
Text File  |  1993-05-21  |  40KB  |  835 lines
  1.  
  2.  
  3. Application Note HP Software Integration Sockets Connecting Foreign
  4. Host Applications to HP Sockets using NCS
  5.  
  6. 1.0     Introduction
  7.  
  8. The purpose of this document is to describe a design for using the
  9. Network Computing System (NCS) to establish communication between
  10. applications running within an HP Sockets domain and an application
  11. running on a platform which is supporte d by NCS but not by HP Sockets.
  12. This platform and the application which runs on it are referred to,
  13. throughout this document, as a foreign host and a foreign ap plication.
  14.  
  15. This document will be primarily useful for technical people who would
  16. like to know how to implement such a system. The reader is assumed to
  17. have a technical understanding of both HP Sockets and NCS. For those
  18. who need it, a brief background of NCS and HP Sockets is provided in
  19. Appendix A.
  20.  
  21. The document begins with an overview of the connection followed by an
  22. in-depth look at each part of the design. This should provide the
  23. reader with a quick understanding of what is involved with building
  24. such a system. Code for a sample implementation is available from HP
  25. for anyone who would like it.
  26.  
  27.  
  28. 2.0     Overview of the NCS and HP Sockets Connection
  29.  
  30. NCS's interprocess communication capability can be used to connect a
  31. foreign application to the HP Sockets domain. The client-server model
  32. eminent in NCS's RPC mechanism provides a good solution for foreign
  33. applications to gain access to the functionality of HP Sockets.
  34.  
  35. In this design, NCS will be used as the communication mechanism between
  36. the foreign host and a machine within the HP Sockets domain (See Figure
  37. 1-1). More spec ifically, the foreign application adaptor, an NCS
  38. client, will issue an HP Socke ts call. The execution of this call is
  39. routed to a gateway server, an NCS server , which will then make the
  40. actual HP Sockets call. The NCS server will contain one procedure for
  41. each of the HP Sockets routines. The foreign application adap tor will
  42. call NCS's remote procedure using the same name and passing the same pa
  43. rameters as if it were the actual HP Sockets call. When the remote
  44. procedure in the server executes, it will turn around and make the real
  45. HP Sockets call, passing the values which were sent to it. After HP
  46. Sockets returns, the return value is sent back to the foreign adaptor
  47. as the return value for the remote procedure. This design allows the
  48. foreign adaptor to have full control of the call into the HP Sockets
  49. domain.
  50.  
  51. This design is a simple design in which the NCS server provides a
  52. gateway connection for one foreign application at a time. This scheme
  53. establishes a direct pip eline from the foreign application through a
  54. gateway server and into the HP Sockets domain. The foreign application
  55. adaptor can exist as a stand- alone process or it can be integrated
  56. into the application just like an ordinary HP Sockets application
  57. adaptor.
  58.  
  59.  
  60.  
  61. *** Object: Untitled
  62.  
  63.  
  64. Figure 1-1
  65.  
  66.  
  67. 2.1  Flow of a typical call from a foreign application to an
  68. application with in the HP Sockets domain
  69.  
  70. The following describes what happens in a typical call from the foreign
  71. application adaptor through NCS to the gateway server and then into HP
  72. Sockets.
  73.  
  74. 1) The foreign application adaptor, an NCS client, makes a remote
  75. procedure call (e.g. SpSendMsg_$NCS). This call could have been
  76. initiated directly from the foreign application or indirectly from a
  77. separate application adaptor process.
  78.  
  79. 2) The remote procedure call (RPC) goes directly into the client stub
  80. routine. This routine acts as if it were the remote procedure, but
  81. instead it marshals the input parameters into an RPC packet.
  82.  
  83. 3) The client stub calls an internal routine which transmits the RPC
  84. packet over the network to the NCS server and then waits for a reply.
  85.  
  86. 4) If the NCS handle is bound to a host, the RPC packet is sent
  87. directly to that host. Once at the host, if the handle specifies a
  88. well-known port, the request goes to that port. Otherwise, the request
  89. goes to the Local Location Broker forwarding port. The LLB forwarding
  90. mechanism will then forward the RPC to the appro priate NCS server. In
  91. this case there is only one, the gateway server.
  92.  
  93. 5) The RPC Runtime Library associated with the server receives the
  94. packet and sends it to the appropriate server stub routine. This
  95. routine unmarshals the input parameters from the request packet into
  96. the data types expected by the server ( the data types specified in the
  97. interface definition).
  98.  
  99. 6) The server stub converts the data into the server's native
  100. representation if it's different from the client's native
  101. representation. For instance, a charact er parameter might be converted
  102. from EBCDIC to ASCII.
  103.  
  104. 7) The server stub then calls the correct remote procedure (e.g.
  105. SpSendMsg_$NCS) .
  106.  
  107. 8) Now execution is finally in the remote procedure. It is here that
  108. the actual HP Sockets call is made (e.g. SpSendMsg).
  109.  
  110. 9) HP Sockets receives the call from the gateway server and performs
  111. the appropriate action.
  112.  
  113. 2.2  Overview of Development Tasks
  114.  
  115. The following is an overview of what tasks need to be done in order to
  116. implement a foreign host connection using NCS.
  117.  
  118.  * Configure the HP Sockets domain to include the gateway server as an
  119. HP Sockets process.
  120.  
  121.  * Use the Network Interface Definition Language (NIDL) to define the
  122. network interface between the foreign host and the gateway server.
  123. After this is complete, run the NIDL file through the NIDL compiler to
  124. produce the client and server stubs.
  125.  
  126.   * Create the gateway server initialization code that registers and
  127. establishes communication with the NCS runtime environment.
  128.  
  129.  * Create the manager section of the gateway server which contains the
  130. actual code for the remote procedures.
  131.  
  132.  * Create a foreign application adaptor as if it were an ordinary HP
  133. Sockets adaptor. However, replace each HP Sockets call with the
  134. corresponding remote procedure call. The name of each remote procedure
  135. is identical to its HP Sockets counterpart except an extension (_$NCS)
  136. is needed. This is necessary otherwise name conflictions will occur on
  137. the gateway server code.
  138.  
  139.  
  140. 3.0     The Design of a Foreign Host Connection
  141.  
  142. The following section takes a closer look at each of the tasks a
  143. developer must do to use NCS as a connection between a foreign host and
  144. the HP Sockets domain.
  145.  
  146. 3.1     HP Sockets Configuration
  147.  
  148. Configuring the HP Sockets domain to include the specification of the
  149. gateway server requires the modification of at least two configuration
  150. files (the Process Definition file, to add the gateway server process,
  151. and the Network Definition file, to add the node that the gateway
  152. server will run on). If the system requires HP Sockets to re-align
  153. data, perform data manipulation, or transfer a file, then additional
  154. information will be needed in the remaining files. For more infor
  155. mation on configuring an HP Sockets domain see chapter 4 of the HP
  156. Software Integration Sockets Programmers Manual.
  157.  
  158. 3.2     NIDL Definition
  159.  
  160. The next task is to use NIDL to specify the network interface between
  161. the foreign application adaptor and the gateway server. Since the goal
  162. is to transparently connect up to the HP Sockets domain, the interface
  163. for each remote procedure should be as close as possible to the
  164. corresponding HP Sockets access routine. The name of each remote
  165. procedure should be the same as the name of each HP Sockets routine.
  166. However, in order to avoid name conflictions on the gateway server, the
  167. name must be different. An extension (_$NCS) is used in the sample
  168. implementat ion provided by HP. For example, figure 1-2 shows a section
  169. of the sample NIDL code which defines the remote procedure for the
  170. SpSendMsg call. Another thing to notice is that the handle is declared
  171. as an implicit_handle and therefore not passed as a parameter to the
  172. remote procedure. This allows the developer to define only the
  173. parameters that are needed for the specific call being emulated. There
  174. is one exception and that is if the message buffer for either
  175. SpSendMsg_$NCS or SpReadQ_$NCS is declared as an open array. If an open
  176. array is used then the size variable, for the last_is attribute, must
  177. also be passed to the remote procedure.
  178.  
  179.  
  180.  
  181. *** Object: code1
  182.  
  183.  
  184. Figure 1-2
  185.  
  186.  
  187. By specifying the message buffer as an array of byte, the foreign
  188. adaptor is able to send multiple data types with the same procedure
  189. call (exactly what HP Sockets allows). However, NCS will not perform
  190. any data conversion since it does not know what types are being passed.
  191. This leaves the burden up to the developer to handle any data
  192. conversion or alignment problems that might occur because of different
  193. data representations between the foreign host and the gateway server.
  194. For more information and a solution to this problem see Appendix B:
  195. Advanced Topics.
  196.  
  197. 3.3     Gateway Server Initialization
  198.  
  199. The server initialization code, which establishes communication with
  200. the NCS run time environment, usually appears in the server's main
  201. procedure. Typically this code starts off by processing the command
  202. line arguments which would probably contain the name of the protocol
  203. being used between the client and the server (for example ip or dds).
  204. After converting the protocol name to its integer representation and
  205. validating it, a socket address is created using the rpc_$use_family
  206. call.
  207.  
  208.         rpc_$use_family(family, &sockaddr, &socklen, &status);
  209.  
  210. The server will then register the socket address with the location
  211. broker so that the forwarding mechanism will know which socket the
  212. server is listening on. The server must also register its manager but
  213. with the RPC Runtime Library using t he rpc_$register_mgr call.
  214.  
  215. The initialization code for the server must then create a cleanup
  216. handler that w ill be executed when a fault occurs. If a signal is
  217. received by the process, the cleanup handler will unregister the server
  218. with the location broker as well as the RPC Runtime Library, before
  219. exiting. Now the server can call rpc_$listen in order to begin
  220. listening for requests.
  221.  
  222.  
  223. 3.4     Manager Section
  224.  
  225. The manager is the section of the server which contains the actual code
  226. for the remote procedures. The manager starts off by defining the entry
  227. point vectors (E PV) through which the routines are called.
  228.  
  229. After this, a routine is implemented for each of the remote procedures
  230. defined in the NIDL file. Most of the routines just call the HP Sockets
  231. routine and then return the status back to the client. One exception is
  232. the SpErrLog_$NCS routine . This routine is passed two parameters, a
  233. message and an integer specifying the length of the message. Since it's
  234. possible for NCS to convert the message from one character
  235. representation to another, the message length should be recomputed
  236. before the actual SpErrLog routine is called. Another exception is the
  237. SpReadQ_ $NCS routine. If the buffer parameter is defined as an open
  238. array, the size variable must be set to the length of the buffer before
  239. returning to the client (See Figure 1-3).
  240.  
  241.  
  242.  
  243. *** Object: code2
  244.  
  245.  
  246. Figure 1-3
  247.  
  248.  
  249. If the buffer in SpSendMsg_$NCS or SpReadQ_$NCS is declared as the
  250. actual type of data that it contains, its possible for NCS to perform
  251. data conversion. Taking this into account, the IList[SpBUF_LEN]
  252. parameter should be reset by the gateway server, before the actual call
  253. to SpSendMsg is made. The SpReadQ_$NCS routine is not so lucky. Since
  254. data conversion occurs on the way back from the gateway server, there
  255. is no way to correctly set the value for the OList[SpBUF_LEN] param
  256. eter. This is something that the developer should watch out for. See
  257. Appendix B: Advanced Topics for more information on this topic.
  258.  
  259. 3.5     Foreign Application Adaptor
  260.  
  261. The first thing that the foreign application adaptor must do is create
  262. and bind a handle to the NCS server that will provide the gateway
  263. service into the HP Sockets domain. The hostname for the NCS server
  264. might be hard coded, passed in on the command line, or found from a
  265. lookup request to the Global Location broker. After converting the name
  266. of the address family into its integer representation, a socket address
  267. can be created by using the socket_$from_name call.
  268.  
  269. socket_$from_name(family, server_hostname, hostname_length,
  270. socket_$unspec_po rt, &sockaddr, &socklen,&status);
  271.  
  272. Now a handle can be allocated and bound to the socket address using the
  273. rpc_$bin d call.
  274.  
  275. gateway_handle = rpc_$bind(&uuid_$nil, &sockaddr, socklen, &status);
  276.  
  277. The rest of the code can be developed as if it were an ordinary
  278. application adaptor. There are only a couple of things that are
  279. different. First of all, instead of using the actual HP Sockets call
  280. the remote procedure is used (i.e. SpInit_$ NCS instead of SpInit).
  281. Secondly, special precautions might be needed for the SpSendMsg_$NCS
  282. and SpReadQ_$NCS calls depending on how the buffer parameter is def
  283. ined. Otherwise each parameter will be initialized and set in the same
  284. way as an ordinary application adaptor. For instance, Figure 1-4 shows
  285. an example of what a call to SpStopProcess_$NCS would look like.
  286.  
  287.  
  288.  
  289. *** Object: code3
  290.  
  291.  
  292. Figure 1-4
  293.  
  294. Creating a foreign host connection, using the design described above,
  295. does present a few limitations. First of all, the HP Sockets system
  296. administration capabilities can not be supported by the foreign host.
  297. This means that the foreign machine will not be able to start and
  298. shutdown the HP Sockets domain. Secondly, since the foreign application
  299. adaptor is not actually running in the HP Sockets domain, the foreign
  300. adaptor cannot be started or stopped by SpStartProcess and
  301. SpStopProcess. Likewise, the foreign application adaptor will not be
  302. able to start the gateway server. Another limitation is that with the
  303. current design, only one application adaptor can be communicating
  304. through the gateway server at a time. Once a SpInit_$NCS call is made,
  305. every call after that point will communicate with HP Sockets under the
  306. logical process name passed in with the initial SpInit_$NCS call.
  307. Although this design does present the above limitations, most systems
  308. would not find them to be a problem. The proposed foreign host
  309. connection using NCS does provide a good functioning gateway for a
  310. foreign application to communicate with the HP Sockets domain.
  311.  
  312. 4.0     Interface to HP Sockets Access Routines
  313.  
  314. HP provides code for a simple implementation of a connection between a
  315. foreign host and the HP Sockets domain using NCS. Table 1-1 specifies
  316. the level of support the sample code offers for each of the access
  317. routines in HP Sockets.
  318.  
  319.  
  320.  
  321. *** Object: cklist
  322.  
  323.  
  324. Table 1-1
  325.  
  326. A.0     Appendix A: Background
  327.  
  328. This section will provide the reader with information about the Network
  329. Computing System and HP Sockets.
  330.  
  331. A.1     Network Computing System (NCS)
  332.  
  333. The Network Computing System (NCS) is a set of software tools which
  334. allows a developer to build distributed applications across a network
  335. of heterogeneous computers. The system uses a client/server model along
  336. with a remote procedure call(RPC) mechanism as the basis for
  337. development.
  338.  
  339. The flow of a remote procedure call from a client to the server can be
  340. seen in Figure 1-5. The RPC paradigm hides the remote aspects of a call
  341. from the client so that ordinary calling conventions are used as if the
  342. remote procedure was actually local to the client. The client stub acts
  343. as the remote procedure but in reality it actually marshals the data
  344. and uses the RPC Runtime Library to call the server. The server just
  345. waits around until it receives a request from a client. When a request
  346. comes in, the server stub unmarshals the data (performing any data type
  347. conversions that are necessary) and calls the appropriate procedure.
  348. After the procedure is complete, the server sends back the results of
  349. the operation to the client. This design allows developers a straight
  350. forward and easy way of implementing distributed applications that need
  351. a synchronized request - response behavior.
  352.  
  353. A major component of NCS is the Network Interface Definition Language
  354. (NIDL) which allows the application developers to define, in a high-
  355. level language, the interface between the client and the server. This
  356. description mainly defines the remote procedures and the type of each
  357. parameter.
  358.  
  359. The NIDL compiler takes the interface definition and produces C source
  360. code for the client and server stubs. These stubs are then linked into
  361. the client and server so that they can perform data conversions,
  362. assemble and disassemble packets, and interact with the RPC Runtime
  363. Library.
  364.  
  365. The RPC Runtime Library is the backbone of NCS. It contains routines
  366. which enable local programs to execute procedures on remote systems.
  367. Most applications do not use many RPC Runtime Library calls directly
  368. but rather indirectly through the client and server stubs.
  369.  
  370. The last major component of NCS is the Local and Global Location
  371. Brokers. These daemons provide NCS applications the ability to be
  372. portable, transparent and protected from network reconfiguration.
  373. Applications use the NCS Location Brokers to locate suitable servers
  374. dynamically at runtime so that applications do not have to hard code
  375. the location of a particular server.
  376.  
  377. The Local Location Broker (LLB) is a daemon that maintains a database
  378. of information about the different types of servers located on the
  379. local host. The LLB provides access to its database and supports the
  380. RPC forwarding mechanism. Clients can send a remote procedure call
  381. directly to the forwarding port on the desired host and the LLB will
  382. automatically forward the call to the appropriate server on the host.
  383. This eliminates the need for a client to know the specific port that a
  384. server uses and therefore allows the server to obtain a port at
  385. runtime.
  386.  
  387. The Global Location Broker (GLB) is a daemon that maintains a database
  388. of information about servers throughout the network. Clients typically
  389. issue lookup requests to the GLB when they do not know exactly were a
  390. server is running in the network. This allows clients to dynamically
  391. find a server which could be moved around the network for various
  392. reasons.
  393.  
  394. The Location Broker concept is the key to the flexibility and
  395. transparency of NCS. Through the use of location brokers, the resulting
  396. client applications are much more portable than with traditional RPC
  397. mechanisms.
  398.  
  399.  
  400.  
  401. *** Object: process
  402.  
  403.  
  404. Figure 1-5
  405.  
  406.  
  407.  
  408. A.2     HP Software Integration Sockets
  409.  
  410. HP Software Integration Sockets (HP Sockets) is a software tool which
  411. provides the ability to integrate new or existing applications in a
  412. network of heterogeneous and homogeneous computers. Flexible data
  413. transfer, data transformation, data manipulation and process control
  414. capabilities provide an environment in which integration can easily be
  415. accomplished between many different types of applications.
  416.  
  417. The system integrator or developer defines an integrated system in HP
  418. Sockets through a set of configuration files. These configuration files
  419. are created with any ordinary editor (such as vi). Information defined
  420. in these files are used by HP Sockets to provide location transparency
  421. for applications as well as manipulate the data into the correct format
  422. expected by the receiving applications. By defining the configuration
  423. data in a series of files, the user can easily change, update, and
  424. maintain this information in one central location without having to
  425. touch the actual application adaptors.
  426.  
  427. The HP Sockets Manager (smain) allows the user to validate the
  428. configuration files, start up and shut down the whole integrated
  429. system, and perform other system management related functions. Once a
  430. configured system is started up, via smain, there are a number of
  431. runtime modules that are started up which handle the actual data
  432. manipulation and transportation of data. HP Sockets creates and
  433. compiles these modules from the information that was supplied by the
  434. configuration files. Performance is dramatically increased for data
  435. translation and manipulation since these modules are actually compiled
  436. instead of interpreted.
  437.  
  438. Applications send and receive messages, data, and files through a
  439. series of 12 access routines. An application adaptor is the user-
  440. written process which is made up of these calls and serves as a bridge
  441. between the application and HP Sockets . The adaptor accesses the
  442. application data and then sends and receives data using the two main
  443. access routines, SpSendMsg and SpReadQ. The data is transparently
  444. manipulated by HP Sockets into the format expected by the receiving
  445. application(s). Table 1-2 lists the 12 access routines along with a
  446. short description of what each one does.
  447.  
  448. Once the adaptors are written and the configuration files developed and
  449. validated by HP Sockets, the developer can use the Command Processor to
  450. simulate a process for testing and debugging. The Command Processor is
  451. accessed from the HP Sockets Manager (smain).
  452.  
  453.  
  454.  
  455. *** Object: fsis
  456.  
  457.  
  458.  
  459.  
  460.  
  461.  
  462. B.0     Appendix B: Advanced Topics
  463.  
  464. This section describes possible solutions for functions that are not
  465. supported by the sample code.
  466.  
  467. B.1  Problem: Since NCS does not support file transfer capability,
  468. there is no way for the foreign application adaptor to send or receive
  469. a file using NCS.
  470.  
  471.      Discussion: Separate solutions must be considered for sending a
  472. file to the HP Sockets domain versus receiving a file from the HP
  473. Sockets domain. The following solution assumes that the foreign host
  474. supports the File Transfer Protocol (FTP) from ARPA services.
  475.  
  476.      Possible solution: (Sending a file to the HP Sockets domain) The
  477. SpSendFile_$NCS manager routine on the gateway server could set up an
  478. FTP connection with the foreign host and upload the file. If the file
  479. transfer was successful, the actual SpSendFile routine could then be
  480. called to let HP Sockets finish transferring the file from the gateway
  481. server to the destination process.
  482.  
  483.      Possible solution:(Receiving a file from the HP Sockets domain) A
  484. file that is sent to the foreign application will be actually sent to
  485. the gateway server. Once the foreign adaptor finds out that a file has
  486. been sent to the gateway server, either with a file notification or a
  487. message from the sending application, the foreign application adaptor
  488. could set up an FTP connection and download the file from the server.
  489.  
  490.  
  491. B.2  Problem: With the current design, there is no way to support file
  492. and message notification to the foreign application. Notification is
  493. enabled and disabled by setting and unsetting the SpControl functions
  494. SpSET_MSG_NOTIFY and SpSET_F ILE_NOTIFY.
  495.  
  496.      Discussion: Since the gateway server is configured in the HP
  497. Sockets domain as the foreign application, the file or message
  498. notification will actually signal the gateway server. However, the
  499. foreign application adaptor is the actual process that needs to be
  500. notified. In order to support file and message notification, there
  501. needs to be a way to send a message from the gateway server to the
  502. foreign host. This is impossible in the current design because the
  503. foreign application adaptor (NCS client) can make remote procedure
  504. calls to the gateway server (NCS server) but the gateway server cannot
  505. issue remote procedure calls to the foreign application adaptor.
  506.  
  507.      Possible solution: The easiest way to solve this problem is to
  508. develop an NCS server on the foreign host machine. This new server
  509. could provide two remote procedures which would notify the foreign
  510. application adaptor that a message or file was waiting for it on the
  511. gateway server. Exactly how this server would notify the foreign
  512. adaptor depends on the interprocess communication capabilities of the
  513. foreign host machine. Using this implementation, the gateway server
  514. would call the correct remote procedure on the foreign host server
  515. whenever it received a signal that a message or file had arrived. The
  516. new foreign host server would notify the foreign adaptor, in what ever
  517. way that it could, that a message or file has been sent to it and is
  518. waiting on the gateway server.
  519.  
  520.  
  521. B.3  Problem: If the buffer parameter for the SpSendMsg_$NCS call is
  522. declared in NIDL as an array of byte, NCS will not perform any
  523. necessary data type conversions.
  524.  
  525.      Discussion: By specifying the buffer parameter as an array of
  526. byte, the application adaptor can send any number of different data
  527. types with the same procedure . This is the closest mapping to the
  528. behavior of the actual HP Sockets SpSendMsg routine. However, NCS
  529. guarantees that it will not perform any conversions on parameters which
  530. are declared as byte. If there happens to be machine differences in
  531. data type representations between the foreign host and the gateway
  532. server, the data could be misinterpreted. The developer can solve this
  533. problem by creating code in the SpSendMsg_$NCS routine which would
  534. handle the data conversion before the actual HP Sockets call is made.
  535. This would allow the gateway server to handle conversions for any
  536. foreign host which has the same data representation. No matter how the
  537. buffer parameter is declared in the NIDL specification, if HP Sockets
  538. needs to perform any data conversion, realignment, or manipulation,
  539. before it gets to the destination process, the data type needs to be
  540. defined in the Data Definition file.
  541.  
  542.  
  543.      Possible solution: The buffer parameter could be specified as the
  544. exact data type that needs to be sent. By specifying the exact type,
  545. NCS will know how and when to perform any data conversions that might
  546. be necessary. If the data type is specified in the NIDL interface
  547. specification, the server will also know what data type is being sent.
  548. If some sort of data conversion occurs, the value of IList [BUF_LEN]
  549. set by the foreign application adaptor might be incorrect. Since the
  550. server will also know what data type is being passed, the server
  551. routine can reset IList[BUF_LEN] to the correct size of the buffer on
  552. the gateway server. One downside to this implementation is that only
  553. one data type can be sent using this procedure. If more than one type
  554. needs to be sent then the developer would need to implement multiple
  555. procedures, one for each type of data (i.e. SpSendMsg1_$NC S,
  556. SpSendMsg2_$NCS, etc.). This is not the most optimal solution since it
  557. adds complexity, creates adaptor code that is less like traditional HP
  558. Sockets adaptor code, and adds quite a bit of repetitious work.
  559.  
  560. A better solution to this problem is to declare the buffer parameter in
  561. NIDL as a union switch. This would allow the developer to specify a
  562. number of different types that the buffer could represent during
  563. runtime. This would provide the adaptor the capability to send multiple
  564. types of data with the same procedure (exactly what HP Sockets
  565. provides). Since NCS knows the exact data type, it could perform any
  566. data conversions that might be necessary. In addition, the gateway
  567. server will be able to use the discriminator so that it will know which
  568. data type is being sent. The server can then reset the IList[BUF_LEN]
  569. parameter in case the size changed during an NCS data type conversion.
  570.  
  571. B.4  Problem: If the buffer parameter for the SpReadQ_$NCS call is
  572. declared in NIDL as an array of byte then NCS will not perform any
  573. necessary data type conversions.
  574.  
  575.      Discussion: The application adaptor can receive any number of
  576. different data types with the same procedure by specifying the buffer
  577. parameter as an array of byte. This is the closest mapping to the look
  578. and feel of the actual HP Sockets Sp ReadQ routine. However, if there
  579. happens to be machine differences in data type representations between
  580. the foreign host and the gateway server, the data could be
  581. misinterpreted unless proper precautions are taken when interpreting
  582. the data within the buffer. The developer could create code in the
  583. SpReadQ_$NCS routine which would handle the data conversion before the
  584. actual call to HP Sockets is made. This would allow the gateway server
  585. to handle any foreign client which has the same data representation.
  586.  
  587. No matter how the buffer parameter is declared in the nidl
  588. specification, if hp sockets needs to perform any data conversion,
  589. realignment, or manipulation, the data type needs to be defined in the
  590. data definition file.
  591.  
  592.      Possible solution: One solution is to define the buffer parameter
  593. as the exact data type that needs to be read. By specifying the exact
  594. type, NCS will know how and when to perform any data conversions. If
  595. the data representation on the server is different than the foreign
  596. adaptor, the value of IList[BUF_LEN] set by the foreign adaptor might
  597. be incorrect. Since the server will know the exact type being read, the
  598. server routine can reset IList[BUF_LEN] to the correct size of the
  599. buffer. This will prevent any unexpected results that might of occurred
  600. if ILi st[BUF_LEN] was set greater than the actual size of the buffer.
  601. A downside to this implementation is that only one data type can be
  602. read using this procedure. I f more than one data type needs to be
  603. read, the developer would need to implement multiple remote procedures,
  604. one for each type of data (i.e. SpReadQ1_$NCS, SpR eadQ2_$NCS, ...).
  605. This is not the most optimal solution for the same reasons that were
  606. discussed above for SpSendMsg. In addition, you may not know exactly
  607. what you have read into the buffer until you test to see what the tag
  608. value is.
  609.  
  610. Another solution to this problem is to declare the buffer parameter in
  611. NIDL as a union switch. This would allow the developer to specify a
  612. number of different types that the buffer could represent during
  613. runtime. This would also provide the adaptor the capability to read
  614. multiple types of data with the same procedure (exactly what HP Sockets
  615. provides). Since NCS would know what type is being passed back to the
  616. client it could perform any data conversion that is necessary . One
  617. catch here is that the gateway server will need to call the actual
  618. SpReadQ routine with a buffer defined large enough for the biggest
  619. type. The server will have to set up some sort of discriminator scheme
  620. with the tag values so that the gateway server knows what type has just
  621. been read. This will allow the gateway server to set the return buffer
  622. parameter and the discriminator so that NCS knows what type is being
  623. passed back to the foreign host. One thing to keep in mind is that the
  624. OList [SpBUF_LEN] variable could be wrong if a data conversion took
  625. place by NCS as the message was transmitted to the foreign adaptor. The
  626. developer should consider the possibility of alignment problems when
  627. performing the actual SpReadQ call. Refer to the HP Sockets Software
  628. Integration Programmer's Manual for more information on this problem.
  629.  
  630.  
  631. B.5  Problem: The data on the foreign host might need to be manipulated
  632. before it is sent over to the gateway server.
  633.  
  634.      Discussion: In some situations, data may need to be manipulated on
  635. the foreign host before it is sent over to the gateway server. One
  636. example is when the internal representation of the data is declared in
  637. a way that prevents NCS from producing marshalling and unmarshalling
  638. code (i.e. trees, linked lists and structures with embedded pointers).
  639.  
  640.      Possible Solution: The developer can use the NIDL transmit_as
  641. attribute to declare a transmitted type for the buffer parameter. This
  642. attribute associates a transmitted type that stubs pass over the
  643. network with a presented type that clients and servers manipulate. The
  644. developer then provides routines that perform conversions between the
  645. presented and transmitted types. The presented type is converted into
  646. the transmitted type for passage over the network. The transmitted type
  647. is then converted back to the presented type before the server receives
  648. it. However, this feature does not provide the full fledged data
  649. manipulation capability which is supported in HP Sockets.
  650.  
  651.  
  652. 1.0  Glossary
  653.  
  654. Access Routines  - The function calls that make up the HP Sockets
  655. access routine library.
  656.  
  657. Application Adaptor - A user-written program that acts as a bridge
  658. between an application and HP Sockets.
  659.  
  660. Application Program - A purchased or user-written software product that
  661. performs specific tasks to achieve a well-defined goal.
  662.  
  663. Binding - The act of designating an object and a server for that object
  664. when mak ing an RPC. Binding in RPC systems is analogous to linking in
  665. conventional procedure calls: it determines the actual code executed
  666. when a call is made. The binding for an RPC is encapsulated in a handle
  667. that is created by the client making the RPC.
  668.  
  669. Broker - An independent intermediary between clients and servers on a
  670. network. The Location Broker is a broker.
  671.  
  672. Client - A process that makes RPCs. See also server.
  673.  
  674. Client Stub - A file generated by the NIDL Compiler that contains
  675. procedures called through the client switch. The client stub marshals
  676. RPC parameters into RPC requests and unmarshals the results when the
  677. RPC returns.
  678.  
  679. Client Switch - A file generated by the NIDL Compiler that contains
  680. procedures named for the operations specified in the network interface.
  681. RPCs in the client are linked to the procedures in the client switch at
  682. compile time. The client switch procedures will then call the
  683. appropriate client stub procedures through the client EPV
  684.  
  685. Command Processor - A module accessed through the HP Sockets Manager
  686. that lets you interactively test the messaging and file transfer to any
  687. process or node within the HP Sockets domain.
  688.  
  689. Daemon - A program designed to run continually as a background process.
  690. Most servers are daemons.
  691.  
  692. Data Manipulation - Manipulation of data into a format acceptable to a
  693. given process.
  694.  
  695. Data Transformation - Transformation of data into a format acceptable
  696. to a specified host computer. Examples are ASCII to EBCDIC, 16-bit
  697. integer to 32-bit integer , proper byte-ordering.
  698.  
  699. Entry Point Vector (EPV) - A record of pointers to the operations in an
  700. interface.
  701.  
  702. Forward - To dispatch an RPC request to a server that exports the
  703. requested interface. The Local Location Broker forwards RPC requests
  704. that are sent to the LLB forwarding port on a server host.
  705.  
  706. Forwarding Port - A port number defined in each address family on which
  707. the LLB forwarding agent listens. RPC requests resulting from RPCs made
  708. with unbound or bound-to-host handles are sent to the forwarding agent.
  709.  
  710. Global Location Broker (GLB) - A database of servers available to a
  711. network.
  712.  
  713. Handle - A temporary local identifier for an object. A handle
  714. represents for a client process the object and the location of a server
  715. that exports one or more interfaces to the object. A handle always
  716. represents a single object, but it may represent different server
  717. locations at different times, or it may not represent a server location
  718. at all. See also binding.
  719.  
  720. Host - A processor attached to a network.
  721.  
  722. HP Sockets Domain - The collection of computers that are configured in
  723. an HP Sockets configuration to work together using the HP Sockets
  724. product. Each computer in the domain is called a node.
  725.  
  726. HP Sockets Manager - The portion of the HP Sockets software that lets
  727. you administer the HP Sockets domain.
  728.  
  729.  
  730. Local Location Broker - A database of objects and servers on a single
  731. host. Each LLB is implemented by a Local Location Broker Daemon (llbd),
  732. which also provides a forwarding agent for servers on the local host.
  733.  
  734. Manager - A set of functions that implements the operations in an
  735. interface for a particular server.
  736.  
  737. Marshal - To construct an RPC request from procedure call parameters.
  738. In NCS, the stubs perform marshaling. See also unmarshal.
  739.  
  740. Message Queue - An HP Sockets queue containing all the incoming
  741. messages for a process. There is one incoming message queue for each
  742. process using HP Sockets. Messages can be sent data by other processes
  743. in the HP Sockets domain.
  744.  
  745. Network Interface Definition Language (NIDL) - A declarative language
  746. for defining network interfaces. NIDL is part of the Network Computing
  747. Architecture. NIDL has two syntaxes, one resembling C and one
  748. resembling Pascal. The NCS/NIDL product from Hewlett-Packard includes
  749. the software needed to build distributed applications that run over
  750. NCS.
  751.  
  752. NIDL Compiler - A program that generates from an interface definition
  753. written in NIDL the stub and header files to implement a network
  754. interface. The NIDL Compiler is part of the Network Computing System
  755. and is included in the NCS/NIDL product from Hewlett-Packard.
  756.  
  757. Open Array - An array whose size is not fixed at compile time. See also
  758. fixed array.
  759.  
  760. Register - To make something known to NCS. For example, servers
  761. register the objects they manage and the interfaces they export with
  762. the RPC runtime and the Location Broker.
  763.  
  764. Remote Procedure Call - An invocation of a remote operation. You can
  765. make remote procedure calls between processes on different hosts or on
  766. the same host.
  767.  
  768. RPC - See remote procedure call.
  769.  
  770.  
  771. RPC Handle - See handle.
  772.  
  773. RPC Runtime - A set of calls that NCS provides to implement and support
  774. its remote procedure call mechanism.
  775.  
  776. Server - A process that exports one or more network interfaces for one
  777. or more objects. A program that provides procedures that can be called
  778. remotely. See also client.
  779.  
  780. Server Stub - A file generated by the NIDL Compiler that contains
  781. procedures called by the RPC runtime in response to an incoming RPC
  782. request. The server stub unmarshals RPC parameters and calls the
  783. appropriate manager function through the manager EPV. When the manager
  784. function returns, the server stub marshals the parameters into an RPC
  785. response returned through the server EPV to the runtime.
  786.  
  787. Socket - A destination for messages on a network. Sockets are labeled
  788. with socket addresses.
  789.  
  790. Stub - A NCS program module that transfers remote procedure calls and
  791. responses between a client and a server. Stubs perform marshalling,
  792. unmarshalling, and data format conversion. Both clients and servers
  793. have stubs. The NIDL Compiler generates client and server stub code
  794. from a network interface definition.
  795.  
  796. Switch - See client switch.
  797.  
  798. Tag Field - A user-defined integer associated with message transfer
  799. requests. Tag field values may be only positive 32-bit signed integers
  800. (not including zero). Use it for user-defined interprocess
  801. communication. For example, a process can uniquely identify data
  802. received from another process. Or, you can prioritize the order in
  803. which messages are removed from the incoming message queue.
  804.  
  805. Transmittable Types - The data types directly supported in NIDL without
  806. use of the transmit_as attribute. Transmittable types have an invariant
  807. interpretation on all systems.
  808.  
  809.  
  810. Unmarshal - To recover procedure call parameters from an RPC request.
  811. In NCS, the stubs perform unmarshalling. See also marshal.
  812.  
  813. Universal Unique Identifier (UUID) - An identifier used by NCS to
  814. identify interfaces, objects, and types. The defining property of a
  815. UUID is its uniqueness; a UUID encodes both the time and the place of
  816. its creation. The algorithms used to generate UUIDs are designed never
  817. to produce the same UUID twice. A UUID can be generated anywhere at
  818. anytime without appealing to a centralized administrator, yet is
  819. guaranteed to be unique .
  820.  
  821. Unregister - To withdraw a registration. See also register.
  822.  
  823. Virtual Adaptor - A server process which has a virtual connection to a
  824. client app lication, and that provides HP Socket functionality on
  825. behalf of the client.
  826.  
  827. 2.0     References
  828.  
  829. HP Software Integration Sockets, Technical Overview (5951-6979) HP
  830. Software Integration Sockets, Programmers Manual (92568-90001) HP
  831. Software Integration Sockets, System Administrator's Manual (92568-
  832. 90002) HP Software Integration Sockets, Self-Paced Tutorial (92568-
  833. 90003) Network Computing System Reference Manual, 010200-A00 Managing
  834. NCS Software, 011895-A01, October 1989
  835.